Amiga Plus Special 21/AMIGAplus Sonderheft 21 (1999)(ICP)(DE)[!].iso/PublicDomain/Emulatoren/ppclibemu/README

Text File | 1999-08-23 | 13KB | 409 lines

---------- ppclibemu V0.6d - The ppc.library emulation for WarpOS ----------


INTRODUCTION
    The importance of WarpOS for PowerPC equipped Amigas is constantly
    increasing. OS3.5 will support WarpOS and future PowerPC G3/G4
    boards will also be based on this kernel.

    Some may like it and some not. I like features in both kernels,
    and in my opinion there must be a possibility to run most of the old
    PowerUp software under WarpOS in future. I'm also sick of rebooting
    my system, when switching the kernel. So the only solution is:
    ppc.library emulation under WarpOS!


FEATURES
    Since V0.5 you can start ELF objects directly (from shell or
    from Workbench). The emulation library installs a LoadSeg()-patch
    which detects and starts ELF objects. But in opposition to the
    original library, the patch can be removed when the library is
    expunged ("avail flush"). ;)

    Of course you can also start ELF objects by using SAS/C's RunElf,
    Ralph Schmidt's PPCLoad or vbcc's PPCRun.

    Since V0.6 the whole PowerUp message system is supported. It's
    slower than the original, but there is still room for improvement.

    The SAS/C HunkObj format is supported since V0.6d. It uses an
    illegal version of 0 in the ELF header's e_ident[EI_VERSION] field.

    The following functions of the original ppc.library are supported:
      o PPCLoadObject
      o PPCUnLoadObject
      o PPCRunObject
      o PPCAllocMem (NOCACHESYNCM68K simulated by allocating chip RAM)
      o PPCFreeMem
      o PPCAllocVec (NOCACHESYNCM68K simulated by allocating chip RAM)
      o PPCFreeVec
      o PPCCreatePool (NOCACHESYNCM68K simulated by allocating chip RAM)
      o PPCDeletePool
      o PPCAllocPooled
      o PPCFreePooled
      o PPCAllocVecPooled
      o PPCFreeVecPooled
      o PPCDebugMode (private, doesn't work like the original)
      o PPCCreateTask
      o PPCDeleteTask
      o PPCGetTaskAttrs (not all tags supported)
      o PPCGetAttrs (PPCINFOTAG_EXCEPTIONHOOK not supported)
      o PPCReadLong
      o PPCWriteLong
      o PPCGetObjectAttrs
      o PPCWriteLongFlush
      o PPCReadWord
      o PPCWriteWord
      o PPCReadByte
      o PPCWriteByte
      o PPCCacheClearE
      o PPCCacheInvalidE
      o PPCCacheTrashE
      o PPCLoadObjectTagList
      o PPCCreatePort
      o PPCDeletePort
      o PPCObtainPort
      o PPCReleasePort
      o PPCWaitPort
      o PPCCreateMessage
      o PPCDeleteMessage
      o PPCGetMessage
      o PPCGetMessageAttr
      o PPCReplyMessage
      o PPCSendMessage

    The following functions of the original PowerUp kernel are supported:
      o PPCAdd64
      o PPCAdd64p
      o PPCAddHead
      o PPCAddHeadSync (implementation might be incorrect)
      o PPCAddTail
      o PPCAddTailSync (implementation might be incorrect)
      o PPCAllocMem (NOCACHESYNCM68K simulated by allocating chip RAM)
      o PPCAllocPooled (No pooled mem under WOS, same as PPCAllocMem)
      o PPCAllocSignal
      o PPCAllocVec (NOCACHESYNCM68K simulated by allocating chip RAM)
      o PPCAllocVecPooled (No pooled mem under WOS, same as PPCAllocVec)
      o PPCAnd64
      o PPCAnd64p
      o PPCAsl64
      o PPCAsl64p
      o PPCAsr64
      o PPCAsr64p
      o PPCAttemptSemaphore
      o PPCAttemptSemaphoreByName
      o PPCAttemptSemaphoreShared
      o PPCCacheFlush
      o PPCCacheFlushAll
      o PPCCacheInvalid
      o PPCCallM68k (Flags ignored. Asynchronous calls are synchronous.)
      o PPCCallOS (Flags ignored. Asynchronous calls are synchronous.)
      o PPCClose
      o PPCCloseLibrary
      o PPCCmp64
      o PPCCmp64p
      o PPCCreateMessage
      o PPCCreatePool
      o PPCCreatePort
      o PPCCreateSemaphore
      o PPCCreateTimerObject
      o PPCDeleteMessage
      o PPCDeletePool
      o PPCDeletePort
      o PPCDeleteTimerObject
      o PPCDeleteSemaphore
      o PPCDivRem64
      o PPCDivRem64p
      o PPCDivs64
      o PPCDivs64p
      o PPCDivu64
      o PPCDivu64p
      o PPCEnqueue
      o PPCEnqueueSync (implementation might be incorrect)
      o PPCFindName
      o PPCFindNameSync (implementation might be incorrect)
      o PPCFindTagItem
      o PPCFindTask
      o PPCFinishTask
      o PPCFreeMem
      o PPCFreePooled
      o PPCFreeSignal
      o PPCFreeVec
      o PPCFreeVecPooled
      o PPCGetAttr
      o PPCGetLibSymbol
      o PPCGetMessage
      o PPCGetMessageAttr
      o PPCGetTagData
      o PPCGetTaskAttr (not all tags supported)
      o PPCGetTimerObject
      o PPCInput
      o PPCInsert
      o PPCInsertSync (implementation might be incorrect)
      o PPCLsl64
      o PPCLsl64p
      o PPCLsr64
      o PPCLsr64p
      o PPCMods64
      o PPCMods64p
      o PPCModu64
      o PPCModu64p
      o PPCMuls64
      o PPCMuls64p
      o PPCMulu64
      o PPCMulu64p
      o PPCNeg64
      o PPCNeg64p
      o PPCNewList
      o PPCNextTagItem
      o PPCObtainPort
      o PPCObtainSemaphore
      o PPCObtainSemaphoreByName
      o PPCObtainSemaphoreShared
      o PPCOpen
      o PPCOpenLibrary
      o PPCOr64
      o PPCOr64p
      o PPCOutput
      o PPCRawDoFmt
      o PPCRead
      o PPCReadByte
      o PPCReadLong
      o PPCReadWord
      o PPCReleasePort
      o PPCReleaseSemaphore
      o PPCRemHead
      o PPCRemHeadSync (implementation might be incorrect)
      o PPCRemove
      o PPCRemoveSync (implementation might be incorrect)
      o PPCRemTail
      o PPCRemTailSync (implementation might be incorrect)
      o PPCReplyMessage
      o PPCRevision
      o PPCSeek
      o PPCSendMessage
      o PPCSetSignal
      o PPCSetTaskAttr (not all tags supported)
      o PPCSetTimerObject
      o PPCSignal (might not work, because of different task definitions)
      o PPCSub64
      o PPCSub64p
      o PPCVersion
      o PPCWait
      o PPCWaitPort
      o PPCWrite
      o PPCWriteByte
      o PPCWriteLong
      o PPCWriteWord
      o PPCXor64
      o PPCXor64p
      o memcpy
      o strcmp
      o strcpy
      o strlen
      o __adddi3
      o __anddi3
      o __ashldi3
      o __ashrdi3
      o __cmpdi2
      o __divdi3
      o __fixdfdi
      o __fixsfdi
      o __fixunsdfdi
      o __fixunssfdi
      o __floatdidf
      o __floatdisf
      o __floatunsdidf
      o __iordi3
      o __lmulq
      o __lshldi3
      o __lshrdi3
      o __moddi3
      o __muldi3
      o __negdi2
      o __qdivrem
      o __subdi3
      o __ucmpdi2
      o __udivdi3
      o __umoddi3
      o __xordi3

    Unimplemented M68k functions will return with d0=0 and PPC
    functions return with r3=0.

    These are still missing:
      o Asynchronous 68k function calls
      o Exception handling, debugger support
      o Loading an starting ELF objects by the PowerPC
      o Port lists
      o PPCprintf and other vararg functions
      o PPCDoMethodA/SuperMethodA
      o Some tags are missing for the GetAttrs and GetTaskAttrs functions.


POWERUP DEVELOPERS
    If you are the author of a program, which doesn't work under
    emulation, then I need your help! Please try to determine the
    reason for crashes or failures in your source and tell me about the
    problem. I think the whole Amiga community would be very grateful!

    By using your source and the debugging facilities of ppclibemu it
    should be not too hard. Refer to the BUGS section for debugging
    informations.


REQUIREMENTS
    o 68040 or 68060
    o CyberstormPPC or BlizzardPPC
    o WarpOS V4 (powerpc.library V15)


BLIZZARD PPC NOTES
    You will get some problems on a BPPC with a new flash ROM, because
    the original ppc.library is a resident module and will be
    initialized during reset.

    The only chance is to use BPPCFix (should be included in the
    WarpOS V4 distribution) and install another resident module, which
    removes the ppc.library from the system before it can initialize
    itself. Refer to INSTALLATION for further informations.

    Afterwards you have a 'clean' system, which allows you to start
    WarpOS without using a Terminator (as with a CSPPC). Please use a
    Terminator setting of '1' or '0'. WarpOS will not work with the
    emulation in terminator-mode '2'.


INSTALLATION
    Just start the "Installer_Script". Or if you want to do it manually:

    Save your original ppc.library:

      > copy libs:ppc.library libs:ppc.library.orig

    Copy the ppc.library emulation from this directory to libs:

      > copy ppc.library libs:

    Set the environment variable powerpc/NoPatch to "1":

      > setenv powerpc/NoPatch 1
      > copy ENV:powerpc/NoPatch ENVARC:powerpc/

    Finally reboot your system to flush the old ppc.library.

    BLIZZARD PPC OWNERS ONLY:
      Disable the original ppc.library resident module with
        > BPPCFix install

      If you want to disable the original library for a longer
      time, you may also put the BPPCFix into your S:Startup-Sequence:
        ; $VER: Startup-Sequence_HardDrive 40.2 (25.2.93)
        ; Startup-Sequence for hard drive systems
        BPPCFix install reboot
        [...]

      If the fix is not already installed, it will do so and
      automatically reboot the system.


USAGE
    Either you install the emulation ppc.library permamently in LIBS:
    or use "loadlib" to temporarily activate the emulation library. It
    can be flushed completely from the system at any time, by using
    "avail flush" (provided that no application needs it anymore).

    Please remove PPCInstall from your startup-sequence. You will get
    the same effect by using "loadlib path:ppc.library", but don't
    place the call before "C:Copy >NIL: ENVARC: RAM:ENV ALL NOREQ" !

    For a check, you might want to try some of the supplied test ELF
    objects, which were compiled by vbcc-ppc. For example:

      > hello_world.elf
      Hello World!

    or:
      > runelf hello_world.elf
      Hello World!

    timerobj.elf demonstrates the usage of TimerObjects.

    objattr_demo is a 68k program for testing the PPCGetObjectAttrs()
    function. For example, you can try to list all symbols of
    hello_world.elf:

      > objattr_demo hello_world.elf
      0x08D45A40      0x00000000
      0x08586860      0x00000000
      0x08587280      0x00000000
      0x085868C0      0x00000000
      0x08586940      0x00000000
      0x08D45B50      0x00000000      __error
      0x08D45C38      0x00000100      parse_cli_args
      [...]

    msgtest is a 68k program which starts an asynchronous PPC task
    (msgtest.elf) to test the message system. It sends one message
    to the PPC task and waits for reply.


COMPATIBILITY
    The emulation is nearly complete, but still there might be some
    programs which don't run. Though, since the implementation of the
    message system emulation in V0.6, there are first life-signs from
    some of the 'difficult' candidates. For example M.A.M.E and IsisPPC
    are starting now, but refuse to work some time later. Since V0.6d the
    SAS/C HunkObj files are supported, which means that the RC5-client
    will run under emulation. Also some more demos, like VA_OffShore,
    are running since this version (not on my P96 system - but it says
    "screen mode not found", so I think it should do on others :).
    The PPC-engine of AmigaAmp doesn't work, because it needs PPCCreateTask()
    on the PPC-side, which is not emulated (wait for V0.7!).

    The following list of programs should work under emulation:

      o ADoomPPC (when started by runelf, use "setenv DOOMWADDIR")
      o VDoom (PPCLoad or old PPCRun only!)
      o ADoM, HereticPPC, HexenPPC
      o Some demos: VAEDies, VAGhost, VA_OffShore, ...
      o musicin, musicout
      o Packers: unlzx, lha, unrar, uuencode, uudecode, etc.
      o Emulators: PPCFrodo, AmigaVGBPPC, PCEmulator, UAE-PPC, Ami-Generator
      o Graphics: SManPPC, PowerView, Benoit, Reflections 4.3
      o Ripley
      o qmap
      o ak-PPC-datatypes, SuperView NG
      o rc5des_PPC
      o PowerUp developer examples
      o PowerUp demos: Plane, Mountain, Memtest


BUGS
    There are still some functions of ppc.library and the PowerUp kernel
    which are not supported (and there might be a lot of bugs in the
    functions which *are* supported :).

    If you get any difficulties (I'm sure you will :), then try to
    isolate the problem by enabling the debugging mode. You can
    enable debugging mode on the 68k-side by using the ppcdbmode
    utility:
      ppcdbmode 1      - enables all error requesters
      ppcdbmode 0x8000 - enables serial debugging (you can use Sushi)
    (or ppcdbmode 0x8001 to enable both).

    You can get full serial debugging (kernel emulation too) by
    exchanging ppc.library with ppc.library.debug. This is the
    recommended method - but execution will be *much* slower.

    If you think that you found a bug, then send me your serial debugging
    output, which you got from Sushi or a terminal. Also give me the name
    of the program and the arguments used. You should be able to determine
    by yourself, if it's a real bug or only an unimplemented function
    which causes the problems.



Frank Wille                  13-May-1999                [e-mail]